Introduction
RenderBoy 1.0 allows you to import and export design files from or to ordinary text files.  Why would you want to do this?  Well, it is an easy way for two people to exchange a design via email.  Just export the design, then email it to a friend.  They can import the file once they receive it.  Other people may want to create a design programmatically via software.  Having a piece of software output a text file is a pretty simple thing to do.  If neither of these capabilities sounds like something you need, feel free to skip this chapter.  And actually, if you are just going to email the export files, you can also skip this chapter, unless you also want to know how to interpret the files.  The main purpose of this chapter is to explain how to interpret the exported text files.

Icky Technical Details
One of my design goals with RenderBoy was to make it as non technical and WYSIWYG as I could.  But,  I'm afraid it's time to learn one or two of the inner workings of RenderBoy.  To understand this chapter, you have no choice.

First, a cartesian (or X,Y,Z) coordinate system.  Yup, RenderBoy has one, and it is used to position and orient all of the objects in your design.  If you don't understand coordinate systems, then you will need to dig up a geometry text book, since I won't try to explain that here.  Remember this picture from the "Design View Manipulation" chapter?  It shows how the front, side, and top views are arranged in 3D space.

Well, suprise!  This is really the X,Y,Z coordinate system! The X axis is the one coming out of the front view.  The Y axis is the one coming out of the side view, and the Z axis is the one coming out of the top view.  Or, if you prefer to think of it in terms of what you see on the screen:

Viewed here, the X-Y-Z coordinate system is arranged as follows:

Front View:  X is out of the screen, Y is right, and Z is up.
Side View: X is left, Y is out of the screen, and Z is up.
Top View: X is down, Y is right, and Z is out of the the screen.

Well, that's enough about coordinate systems.  The next thing to understand is color.  To specify a color, you need to numerically specify the fraction of red, green, and blue which make up the color.  Red, green, and blue are the primary colors of light which are combined to make up all the other colors.  To understand this, I recommend you play with the standard color dialog which you use to change the color of objects in RenderBoy.  It will show you the red, green, and blue components of any color you select.  Apple decided to show each color in a range from zero to 65,535, since that is how it is stored internally.  I let you specify a color as a fraction in the range 0.0 to 1.0, which I think is simpler to use.

Import/Export Limitations
RenderBoy has one main limitation when it comes to importing and exporting files:  It cannot import or export any textures which have been applied to a surface.  If you do export a design file with a texture, RenderBoy will export the name of the texture only.  Then when you import, you will be prompted to manually locate that texture file using the standard file dialog.

How does it work?
When RenderBoy is reading an import file, it just reads it like a book from top to bottom, and does what it says, line by line.  Each line starts with a key word, followed by one or more words or parameters. Together, they tell RenderBoy what to do. Note that all of these words and parameters are case sensitive and must be typed exactly.  For example, if the key word is supposed to be "OBJECT", then the key words "Object", "object", or "OBJECTS" just won't cut it.  The computer is picky.

Also note that any time "the coordinate system" is mentioned, it refers to the X,Y,Z coordinate system defined in the first part of this chapter.

Specifying Object Position
The CENTER keyword is used to specify the center of the next object(s) to be created.  It is followed by three numbers, separated by spaces, and these are the X,Y,Z center of object(s) within the coordinate system.  For example, the following specifies that the next object(s) created should be centered at X=10, y=20, and z=30:

CENTER 10 20 30

If no CENTER is specified, then the center is at (X,Y,Z) = (0,0,0)

Specifying Object Orientation
The ORIENTATION keyword is used to specify the orientation of the next object(s) to be created.  It is followed by three numbers, separated by spaces, and these are the amount of rotation about the X axis, then the Y axis, then the Z axis of the coordinate system.  For example, the following specifies that the next object(s) created should be rotated 10 degrees about the X axis and 20 degrees about the Y axis, and 30 degrees about the Z axis.

ORIENTATION 10 20 30

If no ORIENTATION is specified, then all three orientation angles are zero.

Specifying Object Dimensions
The DIMENSION keyword is used to specify the dimension(s) of the next object(s) to be created.  It is followed by one to three numbers, separated by spaces, and these are interpreted differently, depending on the object(s) which get created.  For objects which are defined by one dimension (like light surces), one parameter is interpreted as the outer diameter.  For objects which are defined by two dimensions (like spheres), the two parameters are interpreted as the inner and outer diameters.  For objects which are defined by three dimensions, the three parameters are either the length, inner  diameter, and outer diameter (like for tubes, cones, and bells) or the length, width, and height (like for blocks, rods, and eggs).  For example, the following specifies that any subsequent two dimension object (sphere) created should have an inner diamter of 20 and an outer diamter of 30.

DIMENSION 20 30

Specifying Object Color
The COLOR keyword is used to specify the color of the next object(s) to be created.  It is followed by three numbers, separated by spaces, and these are the fraction of red, green, and blue in the color of the next object(s) to be created.  For example, the following specifies that the next object(s) created should be yellow, which is equal amounts of red and green, with no blue.

COLOR 1.0  1.0  0.0

If no COLOR is specified, then all three color values are 1.0 which results in a white object.

Specifying Object Surface Properties
Keywords are available to specify the diffusion, reflectance, refraction, and shinyness of regular objects, as well as the intensity of light sources.  All of these keywords are followed by one parameter, which is a fraction value from 0.0 to 1.0.  For example, the following keywords specify that the next objects(s) created should be 20% diffuse, 30% reflective, and 50% refractive. Also note that these three values should always add to 100%.

DIFFUSION 0.2
REFLECTION 0.3
REFRACTION 0.5

The following keyword specifies that the next object(s) created should have a shinyness of 95%.

SHINIYNESS 0.95

The following keyword specifies that the next object(s) (specifically light sources) created should have an a brightness intensity of 80%.

INTENSITY 0.8

Specifying Object Clipping
The CLIPPING keyword is used to specify the clipping of the next object(s) to be created.  It is followed by three words, separated by spaces, and these are the clipping status in the front view(x-axis), side view (y-axis), and top view (z-axis), respectively.  The allowed words are NONE for no clipping, FAR to clip the far half of the object in that view, or NEAR to clip the near half of the object in that view.  For example, the following specifies the next object(s) created should be clipped in the near half of the front view, the far half of the side view, and none of the top view:

CLIPPING NEAR FAR NONE

If no CLIPPING is specified, then no clipping is the default.